General: Forums subtopic: App & System Services > Networking DevForums tag: Network Extension Network Extension framework documentation Routing your VPN network traffic article Filtering traffic by URL sample code Filtering Network Traffic sample code TN3120 Expected use cases for Network Extension packet tunnel providers technote TN3134 Network Extension provider deployment technote TN3165 Packet Filter is not API technote Network Extension and VPN Glossary forums post Debugging a Network Extension Provider forums post Exporting a Developer ID Network Extension forums post Network Extension Framework Entitlements forums post Network Extension vs ad hoc techniques on macOS forums post Network Extension Provider Packaging forums post NWEndpoint History and Advice forums post Extra-ordinary Networking forums post Wi-Fi management: Understanding NEHotspotConfigurationErrorInternal forums post See also Networking Resources for general networking resources, including information about Wi-Fi. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com"

Hi, I’m looking for clarification on TN3134: Network Extension provider deployment, specifically iOS deployment requirements for: packet tunnel provider DNS proxy provider From the documentation: Packet Tunnel Provider App extension (min iOS 9.0): per-app mode requires a managed device DNS Proxy Provider App extension (min iOS 11.0): supervised devices only App extension (min iOS 11.0): per-app mode requires managed devices Issue I implemented a DNS proxy using NEDNSProxyManager. Works as expected in debug builds on a local device Fails to configure when distributed via TestFlight Console Output (TestFlight build) error 10:05:39.872258-0500 nehelper The production version of *** is not allowed to create DNS proxy configurations. Use MDM to create DNS Proxy configurations for the production version of ***. Question Is it possible to distribute a DNS proxy provider for use on non-MDM / non-supervised devices? If not: Is the limitation strictly enforced at distribution/runtime? Is a packet tunnel provider the only viable alternative for App Store distribution? There is a lot of different VPN apps on the App Store that appear to work out of the box without MDM or supervision, which suggests they are using a different deployment model. Thank you for any clarification or guidance!

This discussion is for iOS/iPadOS. I've written an NEAppProxyProvider network extension. I'd like to test it. I thought that using the "NETestAppMapping" dictionary was a way to get there, but when I try to instantiate an NEAppProxyProviderManager to try to install stuff, the console tells me "must be MDM managed" and I get nowhere. So can someone tell me, can I at least test the idea without needing to first get MDM going? I'd like to know if how I'm approaching the core problem even makes sense. My custom application needs to stream video, via the SRT protocol, to some place like youtube or castr. The problem is that in the environment we are in (big convention centers), our devices are on a LAN, but the connection from the LAN out to the rest of the world just sucks. Surprisingly, cellular has better performance. So I am trying to do the perverse thing of forcing traffix that is NOT local to go out over cellular. And traffic that is completely local (i.e. talking to a purely local server/other devices on the LAN) happens over ethernet. [To simplify things, wifi is not connected.] Is an app proxy the right tool for this? Is there any other tool? Unfortunately, I cannot rewrite the code to force everything through Apple's Network framework, which is the one place I know we can say "use cellular." [E.g. URLSession() has absolutely no way of forcing cellular, and even so, the low level streaming library I use is written with raw sockets, and its not feasible for me to rewrite it.] Any other suggestions of how to accomplish this "send non-local traffic to cellular, all local traffic out over ethernet" gratefully welcomed!

Hi, i searched some information about how widgetKit updates widgets using "reloadAllTimelines/reloadAllControls" and i know about daily limit for apps to update their widgets. I only care about how to notify user instantly about vpn status change even if app is terminated and user launch vpn connection from ControlCenter(system widget) or SysSettings, is there a way to update my app's contolCenter widgets from Tunnel if widget and tunnel extensions already have same appGroup defaults?

Hi there, We have been trying to set up URL filtering for our app but have run into a wall with generating the bloom filter. Firstly, some context about our set up: OHTTP handlers Uses pre-warmed lambdas to expose the gateway and the configs endpoints using the javascript libary referenced here - https://developers.cloudflare.com/privacy-gateway/get-started/#resources Status = untested We have not yet got access to Apples relay servers PIR service We run the PIR service through AWS ECS behind an ALB The container clones the following repo https://github.com/apple/swift-homomorphic-encryption, outside of config changes, we do not have any custom functionality Status = working From the logs, everything seems to be working here because it is responding to queries when they are sent, and never blocking anything it shouldn’t Bloom filter generation We generate a bloom filter from the following url list: https://example.com http://example.com example.com Then we put the result into the url filtering example application from here - https://developer.apple.com/documentation/networkextension/filtering-traffic-by-url The info generated from the above URLs is: { "bits": 44, "hashes": 11, "seed": 2538058380, "content": "m+yLyZ4O" } Status = broken We think this is broken because we are getting requests to our PIR server for every single website we visit We would have expected to only receive requests to the PIR server when going to example.com because it’s in our block list It’s possible that behind the scenes Apple runs sporadically makes requests regardless of the bloom filter result, but that isn’t what we’d expect We are generating our bloom filter in the following way: We double hash the URL using fnv1a for the first, and murmurhash3 for the second hashTwice(value: any, seed?: any): any { return { first: Number(fnv1a(value, { size: 32 })), second: murmurhash3(value, seed), }; } We calculate the index positions from the following function/formula , as seen in https://github.com/ameshkov/swift-bloom/blob/master/Sources/BloomFilter/BloomFilter.swift#L96 doubleHashing(n: number, hashA: number, hashB: number, size: number): number { return Math.abs((hashA + n * hashB) % size); } Questions: What hashing algorithms are used and can you link an implementation that you know is compatible with Apple’s? How are the index positions calculated from the iteration number, the size, and the hash results? There was mention of a tool for generating a bloom filter that could be used for Apple’s URL filtering implementation, when can we expect the release of this tool?

Hello, I am developing a URL traffic filtering system. I’ve set up a PIR server following this guide: https://developer.apple.com/documentation/networkextension/setting-up-a-pir-server-for-url-filtering According to this WWDC25 video, it appears that I need to use an OHTTP Gateway: https://developer.apple.com/videos/play/wwdc2025/234/ So, I developed an OHTTP Gateway and verified it using a test client. Following that, I built the app and installed it on a test iPhone based on this sample: https://developer.apple.com/documentation/networkextension/filtering-traffic-by-url However, I cannot find any settings related to the OHTTP URL within this sample. How should I proceed with the OHTTP configuration in this case? Thank you.

I am seeing an issue with NETransparentProxyProvider where the extension successfully transitions from sleep to wake, but stops receiving handleNewFlow(_:) calls. Only below two methods gets called, We don't apply rules in these methods: override func wake() override func sleep(completionHandler: @escaping () -> Void) This breaking complete proxy workflow as it stops intercepting traffics. We are not observing this issues always. FYI: com.apple.developer.endpoint-security.client is not present in .entitlement file. I am not sure adding this will help. Any possibilities nesessionmanager might fail to re-bind the traffic rules for this extensions? Any thing we can do to avoid this issues?

Hello, How does macOS handle coexistence between multiple Transparent Proxy providers from different vendors if their network rules overlap and one provider modifies the traffic? Thank you in advance!

I'm implementing a NEDNSProxyProvider on macOS 15.x and macOS 26.x. The flow works correctly up to the last step — returning the DNS response to the client via writeDatagrams. Environment: macOS 15.x, 26.x Xcode 26.x NEDNSProxyProvider with NEAppProxyUDPFlow What I'm doing: override func handleNewFlow(_ flow: NEAppProxyFlow) -> Bool { guard let udpFlow = flow as? NEAppProxyUDPFlow else { return false } udpFlow.readDatagrams { datagrams, endpoints, error in // 1. Read DNS request from client // 2. Forward to upstream DNS server via TCP // 3. Receive response from upstream // 4. Try to return response to client: udpFlow.writeDatagrams([responseData], sentBy: [endpoints.first!]) { error in // Always fails: "The datagram was too large" // responseData is 50-200 bytes — well within UDP limits } } return true } Investigation: I added logging to check the type of endpoints.first : // On macOS 15.0 and 26.3.1: // type(of: endpoints.first) → NWAddressEndpoint // Not NWHostEndpoint as expected On both macOS 15.4 and 26.3.1, readDatagrams returns [NWEndpoint] where each endpoint appears to be NWAddressEndpoint — a type that is not publicly documented. When I try to create NWHostEndpoint manually from hostname and port, and pass it to writeDatagrams, the error "The datagram was too large" still occurs in some cases. Questions: What is the correct endpoint type to pass to writeDatagrams on macOS 15.x, 26.x? Should we pass the exact same NWEndpoint objects returned by readDatagrams, or create new ones? NWEndpoint, NWHostEndpoint, and writeDatagrams are all deprecated in macOS 15. Is there a replacement API for NEAppProxyUDPFlow that works with nw_endpoint_t from the Network framework? Is the error "The datagram was too large" actually about the endpoint type rather than the data size? Any guidance would be appreciated. :-))

I have a macOS VPN app with a Network Extension (packet tunnel provider) distributed outside the App Store via Developer ID. Everything works perfectly when running from Xcode. After archiving and exporting for Developer ID distribution, the extension launches but immediately gets killed by nesessionmanager. The error: Signature check failed: code failed to satisfy specified code requirement(s) followed by: started with PID 0 status changed to disconnected, last stop reason Plugin failed What makes this interesting: the extension process does launch. AMFI approves it, taskgated-helper validates the provisioning profile and says allowing entitlement(s) due to provisioning profile, the sandbox is applied, PacketTunnelProvider is created — but then Apple's Security framework internally fails the designated requirement check and nesessionmanager kills the session. Key log sequence: taskgated-helper: Checking profile: Developer ID - MacOS WireGuardExtension taskgated-helper: allowing entitlement(s) for com.xx.xx.WireGuardNetworkExtension due to provisioning profile (isUPP: 1) WireGuardNetworkExtensionMac: AppSandbox request successful WireGuardNetworkExtensionMac: creating principle object: PacketTunnelProvider WireGuardNetworkExtensionMac: Signature check failed: code failed to satisfy specified code requirement(s) nesessionmanager: started with PID 0 error (null) nesessionmanager: status changed to disconnected, last stop reason Plugin failed Setup: macOS 15, Xcode 16 Developer ID Application certificate Manual code signing, Developer ID provisioning profiles with Network Extensions capability Extension in Contents/PlugIns/ (standard appex, not System Extension) Extension entitlement: packet-tunnel-provider-systemextension NSExtensionPointIdentifier: com.apple.networkextension.packet-tunnel codesign --verify --deep --strict PASSES on the exported app Hardened runtime enabled on all targets What I've verified: Both app and extension have matching TeamIdentifier Both are signed with the same Developer ID Application certificate The designated requirement correctly references the cert's OIDs The provisioning profiles are valid and taskgated-helper explicitly approves them No custom signature validation code exists in the extension — the "Signature check failed" comes from Apple's Security framework What I've tried (all produce the same error): Normal Xcode archive + export (Direct Distribution) Manual build + sign script (bypassing Xcode export entirely) Stripping all signatures and re-signing from scratch Different provisioning profiles (freshly generated) Comparison with official WireGuard app: I noticed the official WireGuard macOS app (which works with Developer ID) uses packet-tunnel-provider (without -systemextension suffix) in its entitlements. My app uses packet-tunnel-provider-systemextension. However, I cannot switch to the non-systemextension variant because the provisioning profiles from Apple Developer portal always include the -systemextension variants when "Network Extensions" capability is enabled, and AMFI rejects the mismatch. Questions: Is there a known issue with packet-tunnel-provider-systemextension entitlement + PlugIn-based Network Extension + Developer ID signing? Should the extension be using packet-tunnel-provider (without -systemextension) for Developer ID distribution? If so, how do I get a provisioning profile that allows it? The "Signature check failed" happens after taskgated-helper approves the profile — what additional code requirement check is the NE framework performing, and how can I satisfy it? Any guidance would be appreciated. I've exhausted all signing approaches I can think of.

Hello, Is it possible for a Network Extension (running in its sandbox) to act as a client for an XPC service hosted by a Launch Daemon (e.g., to offload data processing)? Are there any specific sandbox restrictions or entitlement requirements for this type of XPC communication? Thank you in advance!

The M5 Pro does not connect to the Wi-Fi AP using RADIUS when NetworkExtension Activiate. The M1 and M2 Pro worked, but only the M5 Pro MacBook Pro did not work. If you deactivate NetworkExtension, it connects to the AP, and afterwards, it works even if you activate NetworkExtension.

I'm developing a macOS security tool using NEFilterDataProvider as a system extension. On macOS 26 beta (25E241), sysextd consistently rejects my extension with: sysextd: no policy, cannot allow apps outside /Applications Configuration: App installed in /Applications/ Signed with Developer ID Application (693DSH8GN5) Entitlement: com.apple.developer.networking.networkextension = content-filter-provider com.apple.developer.system-extension.install = true Developer Mode enabled on test machine Comparison with Little Snitch: Little Snitch runs correctly on the same machine. Key differences I found: Little Snitch uses content-filter-provider-systemextension instead of content-filter-provider Little Snitch has com.apple.security.app-sandbox = false Both signed with Developer ID Application When I switch to content-filter-provider-systemextension, Xcode rejects every provisioning profile because none match that entitlement value, and the Developer Portal doesn't expose fine-grained control over the Network Extensions array values. Questions Is content-filter-provider-systemextension the correct entitlement for system extensions on macOS 26? How should the provisioning profile be configured to support it? Is there a known sysextd issue on macOS 26 beta causing this regardless of configuration? Is there - somewhere! - a guide on how to build such an extension? Thanks in advance for your help.

In my Notification Service Extension I'm doing two things in parallel inside didReceive(_:withContentHandler:): Downloading and attaching a rich media image (the standard content modification work) Firing a separate analytics POST request (fire-and-forget I don't wait for its response) Once the image is ready, I call contentHandler(modifiedContent). The notification renders correctly. What I've observed (via Proxyman) is that the analytics POST request completes successfully after contentHandler has already been called. My question: Why does this network request complete? Is it because: (a) The extension process is guaranteed to stay alive for the full 30-second budget, even after contentHandler is called so my URLSession task continues executing during the remaining time? (b) The extension process loses CPU time after contentHandler but remains in memory for process reuse and the request completes at the socket/OS level without my completion handler ever firing? (c) Something else entirely? I'd like to understand the documented behaviour so I can decide whether it's safe to rely on fire-and-forget network requests completing after contentHandler, or whether I need to ensure the request finishes before calling contentHandler.

Based on https://developer.apple.com/documentation/networkextension/nednssettings/searchdomains , we expect the values mentioned in searchDomains to be appended to a single label DNS query. However, we are not seeing this behavior. We have a packetTunnelProvider VPN, where we set searchDomains to a dns suffix (for ex: test.com) and we set matchDomains to applications and suffix (for ex: abc.com and test.com) . When a user tries to access https://myapp , we expect to see a DNS query packet for myapp.test.com . However, this is not happening when matchDomainsNoSearch is set to true. https://developer.apple.com/documentation/networkextension/nednssettings/matchdomainsnosearch When matchDomainsNoSearch is set to false, we see dns queries for myapp.test.com and myapp.abc.com. What is the expected behavior of searchDomains?

I added a Content Filter to my app, and when running it in Xcode (Debug/Release), I get the expected permission prompt: "Would like to filter network content (Allow / Don't Allow)". However, when I install the app via TestFlight, this prompt doesn’t appear at all, and the feature doesn’t work. Is there a special configuration required for TestFlight? Has anyone encountered this issue before? Thanks!

Hello, I have implemented a URL Filter using the sample provided here: Filtering Traffic by URL. I am also using an App Group to dynamically manage the Bloom filter and block list data. However, when I update my block list URLs and create a new Bloom filter plist in the App Group, the extension does not seem to use the updated Bloom filter even after the prefetch interval expires. Also for testing purpose can I keep this interval to 10 mins or below ?

Dear Sir/Madam, Thank you for your support. I have reviewed the documentation for Local Push Connectivity (see URL below) and, following the instruction in the "Important" section to "Request this entitlement from the Entitlement Request Page," I completed the application process for this Entitlement on March 11, 2026. [Local push connectivity] https://developer.apple.com/documentation/networkextension/local-push-connectivity?language=objc#Supporting-APNs-and-local-push-connectivity-in-one-app Subsequently, on March 13, 2026, I received the following reply from Apple: Sub : Re: Requesting Network Extension App Push Entitlement From: Local Push Review Sent: Friday, March 13, 2026 4:09 AM Hi, Thank you for your interest in the Local Push Connectivity entitlement. Your entitlement request has been approved for: Team ID: NWKYYYYYYY Technical documentation on this API is available here: -(Omission) - Best Regards, Apple Developer Relations My understanding is that upon approval of this application, an "Entitlements" field should be added to the input fields for creating provisioning profiles. However, as of today(March 18, 2026), it has not yet been added. Will the Entitlements field be added if I simply wait? My account (Apple ID), which submitted the application, belongs to three Team IDs. For convenience, I will refer to them as Team ID SV3XXXXXXX, Team ID NWKYYYYYYY, and Team ID WEJZZZZZZZ. The application status for Entitlements for each Team ID is as follows: Team ID SV3XXXXXXX Entitlements: Present. Applied for Entitlements on February 6, 2021. (Received "Re: Requesting Network Extension App Push Entitlement" email on February 6, 2021) Team ID NWKYYYYYYY Entitlements: Not present. Applied for Entitlements on March 13, 2026. (Received "Re: Requesting Network Extension App Push Entitlement" email on March 13, 2026) Team ID WEJZZZZZZZ Entitlements: Present. No record (email) of applying for Entitlements. Because of this, I am concerned that the Entitlements applied for Team ID NWKYYYYYYY may have been mistakenly granted to Team ID WEJZZZZZZZ, and I am inquiring about this. Will the Entitlements field for Team ID NWKYYYYYYY be added if I simply wait? Thank you in advance.

I haven’t been able to get this to work at any level! I’m running into multiple issues, any light shed on any of these would be nice: I can’t implement a bloom filter that produces the same output as can be found in the SimpleURLFilter sample project, after following the textual description of it that’s available in the documentation. No clue what my implementation is doing wrong, and because of the nature of hashing, there is no way to know. Specifically: The web is full of implementations of FNV-1a and MurmurHash3, and they all produce different hashes for the same input. Can we get the proper hashes for some sample strings, so we know which is the “correct” one? Similarly, different implementations use different encodings for the strings to hash. Which should we use here? The formulas for numberOfBits and numberOfHashes give Doubles and assign them to Ints. It seems we should do this conversing by rounding them, is this correct? Can we get a sample correct value for the combined hash, so we can verify our implementations against it? Or ignoring all of the above, can we have the actual code instead of a textual description of it? 😓 I managed to get Settings to register my first attempt at this extension in beta 1. Now, in beta 2, any other project (including the sample code) will redirect to Settings, show the Allow/Deny message box, I tap Allow, and then nothing happens. This must be a bug, right? Whenever I try to enable the only extension that Settings accepted (by setting its isEnabled to true), its status goes to .stopped and the error is, of course, .unknown. How do I debug this? While the extension is .stopped, ALL URL LOADS are blocked on the device. Is this to be expected? (shouldFailClosed is set to false) Is there any way to manually reload the bloom filter? My app ships blocklist updates with background push, so it would be wasteful to fetch the filter at a fixed interval. If so, can we opt out of the periodic fetch altogether? I initially believed the API to be near useless because I didn’t know of its “fuzzy matching” capabilities, which I’ve discovered by accident in a forum post. It’d be nice if those were documented somewhere! Thanks!!

I’m encountering a persistent issue with my Network Extension (specifically NEFilterDataProvider) and would really appreciate any insights. The extension generally works as expected, but after some time — especially after sleep/wake cycles or network changes — a global network outage occurs. During this state, no network traffic works: pings fail, browsers can’t load pages, etc. As soon as I stop the extension (by disabling it in System Preferences), the network immediately recovers. If I re-enable it, the outage returns instantly. I’ve also noticed that once this happens, the extension stops receiving callbacks like handleNewFlow(), and reinstalling the app or restarting the extension doesn’t help. The only thing that resolves the issue is rebooting the system. After reboot, the extension works fine again — until the problem reoccurs later. I asked AI about this behavior, and it suggested the possibility that the kernel might have marked the extension as untrusted, causing the system to intentionally block all network traffic as a safety mechanism. Has anyone experienced similar behavior with NEFilterDataProvider? Could there be a way to detect or prevent this state without rebooting? Is there any logging or diagnostic data I should collect when it happens again? Any guidance or pointers would be greatly appreciated. Thanks in advance!

Error 8 in the NEHotspotConfigurationError domain is .internal, aka NEHotspotConfigurationErrorInternal. This error typically indicates that something went wrong in some sort of expected way, but we decided not to surface the exact cause [1]. This has come up a bunch of times before on the forums, and I have various titbits to share. To start, I want to address some specific cases: You’ll see this error if your app isn’t signed with the com.apple.developer.networking.HotspotConfiguration entitlement. To fix this, use Xcode’s Signing & Capabilities editor to add the Hotspot capability to your app. Historically developers reported a situation where once they encountered the error it would show up consistently, but then it would go away on restarting the device. If you see behaviour like that, that’s definitely a bug and I encourage you to file it as such. I have more about filing such bugs in Filing a Wi-Fi Bug Report. Of course, you have to wait to reproduce the error again before you’ll be able to file that bug, because the act of restarting cleared the issue. I’ve seen reports where such problems only occur on a specific type of device, for example, on iPhone 16 but not on earlier or later iPhones. That’s definitely something that Apple should investigate, and I recommend that you file a bug about it. If the problem is being reported by your users but you can’t reproduce it yourself, consider the various suggestions in Using a Sysdiagnose Log to Debug a Hard-to-Reproduce Problem. Assuming you’re still here (-: the next step is to determine whether the problem is specific to NEHotspotConfigurationManager or not. Try joining the accessory’s network from Settings > Wi-Fi. Does that also have problems? If so, that’s not something we can help you with here on the forums. The focus of the Apple Developer Forums is primarily to help developers with the APIs in Apple’s various platform SDKs [2]. We’re not set up to help accessory developers with Wi-Fi issues. However, there are still things you can do, as I explain in Filing a Wi-Fi Bug Report. At this point you have an error that: Persists across restarts Happens with all Apple devices You can reproduce Only affects NEHotspotConfigurationManager If that’s correct then there are a couple of things you might look at: Coerce the error to an NSError and print that. Does it reveal anything interesting? Also check the underlying error property (NSUnderlyingErrorKey) for hints. When reproducing the error, monitor the system log for log entries in the com.apple.networkextension subsystem. Do those offer any clues? Note For lots of hints and tips about the system log, see Your Friend the System Log. And finally, if you have questions about this case, feel free to start a thread here on the forums and we’ll try to help you out. Put it in the App & System Services > Networking subtopic and tag it with Network Extension. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" [1] There’s also the .unknown error. See this post for a brief summary of the difference. [2] And with Apple tools and some developer-oriented services. Revision History 2026-03-18 Added a missing entitlement bullet to the specific case list. 2026-03-17 First posted.